One

主题

2025-03-062025-06-26指南指南
3055
13m
Get...

Markdown 拓展 ​

VitePress 使用 markdown-it来对 Markdown 进行解析和渲染，最终转为 Vue 组件。

markdown-it是一款功能强大的 Markdown 解析器，支持丰富的 Markdown 语法，能够轻松将 Markdown 文本转换为 HTML 格式，并提供了许多语法扩展和插件。如果希望文章页拓展一些新的功能、UI，那么可以利用它拦截并处理 Markdown 生成的 HTML。

阅读 VitePress 的代码可以发现，它利用 markdown-it添加了代码块高亮、代码块行号、Tip 容器等功能，在 VitePress 官网的 Markdown 拓展里，已经详细介绍了 VitePress 支持 Markdown 额外拓展的功能。

下面介绍的仅仅是 Teek 实现的 Markdown 拓展。

Teek 也提供了几个 Markdown 插件，分别为：

  • TODO 待办列表
  • center 内容居中容器
  • right 内容居右容器
  • note 容器
  • shareCard 分享卡片
  • imgCard 图文卡片
  • navCard 导航卡片
  • demo 容器
  • ...

center、right、note容器是一种简单的 Markdown 容器（不改变内容，只给内容加样式），Teek 支持定义类似的容器，具体请看 自定义容器。

shareCard、imgCard、navCard是一种较为复杂的 Markdown 容器（改变内容和样式），如果你也想定义类似的容器，可以阅读这三个插件的代码，它们的代码逻辑非常相似且简单，只需要会编写 HTML、CSS，就可以实现一个复杂容器。

TODO 待办列表 ​

输出：

  • 吃饭
  • 睡觉
  • 打豆豆

输入：

markdown
-[] 吃饭-[] 睡觉-[x] 打豆豆

确保 []里有一个空格。

提示

支持所有列表语法，如：1.、-、+、*等。

内容居中容器 ​

输出：

Markdown 拓展

Markdown 拓展 ​

（这是二级标题）

输入：

markdown
:::centerMarkdown 拓展::::::center## Markdown 拓展（这是二级标题）:::

内容居右容器 ​

输出：

@Teek

摘要

很久之前，我决定踏上的这条路，映照了我与未来的因果。

2021-11-13 @Teek

输入：

markdown
:::right@Teek::::::tip 摘要很久之前，我决定踏上的这条路，映照了我与未来的因果。:::right2021-11-13 @Teek:::

笔记容器 ​

笔记容器和 VitePress 的 Github NOTE容器样式一样，Teek 将其转为 :::note启用。

输出：

NOTE

这是一个笔记 Note 容器。

输入：

markdown
:::note这是一个笔记 Note 容器。:::

shareCard 分享卡片 ​

分享卡片容器，可用于 友情链接、项目推荐、诗词展示等。

输出：

输入：

markdown
:::shareCard```yaml
- name: George Chan
  desc: 让我给你讲讲他的传奇故事吧
  avatar: https://z3.ax1x.com/2021/09/30/4oKMVI.jpg
  link: https://cyc0819.top/
  bgColor: "#FFB6C1"
  textColor: "#621529"

- name: butcher2000
  desc: 即使再小的帆，也能远航
  avatar: https://gcore.jsdelivr.net/gh/Kele-Bingtang/static/user/20211029181901.png
  link: https://blog.csdn.net/weixin_46827107
  bgColor: "#CBEAFA"
  textColor: "#6854A1"

- name: Evan's blog
  desc: 前端的小学生
  avatar: https://gcore.jsdelivr.net/gh/xugaoyi/image_store/blog/20200103123203.jpg
  link: https://xugaoyi.com/
  bgColor: "#B9D59C"
  textColor: "#3B551F"
```:::

语法 ​

markdown
:::shareCard <每行显示数量 |auto>```yaml
- name: 名称
  desc: 描述
  avatar: https://xxx.jpg # 头像，可选
  link: https://xxx/ # 链接，可选
  bgColor: "#CBEAFA" # 背景色，可选，默认 var(--vp-c-gray-1)。颜色值有 # 号时请添加引号
  textColor: "#6854A1" # 文本色，可选，默认 var(--vp-c-text-1)
```:::
markdown
:::shareCard <每行显示数量 |auto>```yaml
config:
  cardNum: 2 # 每行显示的卡片数量，默认为 auto，可在容器名字后面添加，如 ::: shareCard 3
  target: _blank # 跳转方式，默认为 _blank，仅支持 _blank | _self
  cardGap: 20 # 每行卡片之间的间隔，默认为 20
  showCode: false # 是否显示代码块，默认为 false

data:
  - name: 名称
    desc: 描述
    avatar: https://xxx.jpg # 头像，可选
    link: https://xxx/ # 链接，可选
    bgColor: "#CBEAFA" # 背景色，可选，默认 var(--vp-c-gray-1)。颜色值有 # 号时请添加引号
    textColor: "#6854A1" # 文本色，可选，默认 var(--vp-c-text-1)
```:::
ts
exportdeclarenamespaceShareCard{exportinterfaceConfig{cardNum?:number|"auto";target?:"_blank"|"_self";cardGap?:number;showCode?:boolean;}exportinterfaceItem{name:string;desc:string;avatar?:string;link?:string;bgColor:string;textColor:string;}}
  • <每行显示数量 |auto>
    • 当为空或为 auto时，自动根据文档宽度进行适配
    • 为数字时，表示每行最多显示多少个，选值范围 1 ~4（自带自适应功能：根据屏幕宽度减少每行显示数量）
  • 代码块需指定语言为 yaml

imgCard 图文卡片 ​

图文卡片容器，可用于 项目展示、产品展示等。

输出：

标题

描述内容描述内容描述内容描述内容

Teek

标题

描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容

Teek

标题

描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容

Teek

标题

描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容

输入：

yaml
:::imgCard```yaml
- img: https://vp.teek.top/blog/bg1.webp
  link: https://vp.teek.top
  name: 标题
  desc: 描述内容描述内容描述内容描述内容
  author: Teek
  avatar: https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar1.png
- img: https://vp.teek.top/blog/bg2.webp
  link: https://vp.teek.top
  name: 标题
  desc: 描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容
  author: Teek
  avatar: https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar1.png
- img: https://vp.teek.top/blog/bg2.webp
  link: https://vp.teek.top
  name: 标题
  desc: 描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容
  author: Teek
  avatar: https://testingcf.jsdelivr.net/gh/Kele-Bingtang/static/user/avatar1.png
- img: https://vp.teek.top/blog/bg3.webp
  link: https://vp.teek.top
  name: 标题
  desc: 描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容描述内容
```:::

语法 ​

markdown
:::imgCard <每行显示数量 |auto>```yaml
- img: https://abc.jpg # 图片地址
  link: https://abc.com # 链接地址
  name: 标题
  desc: 描述 # 可选
  author: 作者名称 # 可选
  avatar: https://abc.jpg # 作者头像，可选
```:::
markdown
:::imgCard <每行显示数量 |auto>```yaml
config:
  cardNum: 2 # 每行显示的卡片数量，默认为 auto，可在容器名字后面添加，如 ::: imgCard 3
  target: _blank # 跳转方式，默认为 _blank，仅支持 _blank | _self
  lineClamp: 2 # 显示描述信息的行数，默认为 2
  cardGap: 20 # 每行卡片之间的间隔，默认为 20
  imgHeight: auto # 图片宽度，默认为 auto。仅图文卡片支持该配置项
  objectFit: cover # 设置图片的填充方式，支持 cover | fill | contain | scale-down | none，默认为 cover
  showCode: false # 是否显示代码块，默认为 false

data:
  - img: https://abc.jpg # 图片地址
    link: https://abc.com # 链接地址
    name: 标题
    desc: 描述 # 可选
    author: 作者名称 # 可选
    avatar: https://abc.jpg # 作者头像，可选
```:::
ts
exportdeclarenamespaceImgCard{exportinterfaceConfig{cardNum?:number|"auto";target?:"_blank"|"_self";imgHeight?:string;objectFit?:"cover"|"fill"|"contain"|"scale-down"|"none";lineClamp?:number;cardGap?:number;showCode?:boolean;}exportinterfaceItem{img:string;link?:string;name:string;desc?:string;author?:string;avatar?:string;}}
  • <每行显示数量 |auto>
    • 当为空或为 auto时，自动根据文档宽度进行适配
    • 为数字时，表示每行最多显示多少个，选值范围 1 ~4（自带自适应功能：根据屏幕宽度减少每行显示数量）
  • 代码块需指定语言为 yaml

导航卡片容器，可以用于制作 导航站点。

输出：

百度

百度——全球最大的中文搜索引擎及最大的中文网站，全球领先的人工智能公司

搜索引擎
Google

全球最大的搜索引擎公司

搜索引擎

输入：

yaml
:::navCard```yaml
- name: 百度
  desc: 百度——全球最大的中文搜索引擎及最大的中文网站，全球领先的人工智能公司
  link: http://www.baidu.com/
  img: https://www.baidu.com/favicon.ico
  badge: 搜索引擎
- name: Google
  desc: 全球最大的搜索引擎公司
  link: http://www.google.com/
  img: https://ts1.cn.mm.bing.net/th/id/R-C.58c0f536ec073452434270fb559c3f8c?rik=SnOUNtUtPLX6ww&riu=http%3a%2f%2fwww.sz4a.cn%2fPublic%2fUploads%2fimage%2f20230303%2f1677839482835474.png&ehk=J1lqoeszPGEWzDOSZQ3JxzXsklfd0QzgrJu6ZVvESKk%3d&risl=&pid=ImgRaw&r=0
  badge: 搜索引擎
  badgeType: tip
```:::

语法 ​

markdown
:::navCard <每行显示数量 |auto>```yaml
- name: 标题
  desc: 描述
  link: 链接地址 # 可选
  img: 图片地址 # 可选
  badge: 徽章内容 # 可选
  badgeType: 徽章类型 # 可选
```:::
markdown
:::imgCard <每行显示数量 |auto>```yaml
config:
  cardNum: 2 # 每行显示的卡片数量，默认为 2，可在容器名字后面添加，如 ::: navCard 3
  target: _blank # 跳转方式，默认为 _blank，仅支持 _blank | _self
  lineClamp: 2 # 显示描述信息的行数，默认为 2
  cardGap: 20 # 每行卡片之间的间隔，默认为 20
  showCode: false # 是否显示代码块，默认为 false

data:
  - name: 标题
  desc: 描述
  link: 链接地址 # 可选
  img: 图片地址 # 可选
  badge: 徽章内容 # 可选
  badgeType: 徽章类型 # 可选
```:::
ts
exportdeclarenamespaceNavCard{exportinterfaceConfig{cardNum?:number|"auto";target?:"_blank"|"_self";lineClamp?:number;cardGap?:number;showCode?:boolean;}exportinterfaceItem{name:string;desc:string;img?:string;link?:string;badge?:string;badgeType?:"info"|"tip"|"warning"|"danger";}}
  • <每行显示数量 |auto>
    • 当为空或为 auto时，自动根据文档宽度进行适配
    • 为数字时，表示每行最多显示多少个，选值范围 1 ~4（自带自适应功能：根据屏幕宽度减少每行显示数量）
  • 代码块需指定语言为 yaml

Video 容器 ​

Video容器可以快速嵌入不同平台的视频：

  • bilibili：Bilibili 视频
  • tencent：腾讯视频
  • youku：优酷视频
  • youtube：YouTube 视频
  • vimeo：Vimeo 视频
  • xigua：西瓜视频
  • 自定义视频链接

以 bilibili为例，输出：

输入：

markdown
:::video bilibiliBV11e411m7e8:::

自定义视频链接，输出：

输入：

markdown
:::videohttps::::

语法 ​

markdown
:::video <视频平台标识><视频 ID>:::
markdown
:::video<自定义视频链接>:::
最近更新